Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
A pass on simplification of the main spec... pull out most of the
vocabulary definition to the activitystream2-vocabulary document, begin extracting out the best practices information to a separate document.
- Loading branch information
Showing
3 changed files
with
660 additions
and
989 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,251 @@ | ||
<section id="linguistic-forms" class="appendix informative"> | ||
<h2>Linguistic Forms</h2> | ||
|
||
<p> | ||
The Activity Streams format has been intentionally designed to be | ||
flexible in how machine-readable statements about past, present or | ||
future actions can be expressed. Implementations will often translate | ||
Activity Statements into human-readable sentences such as | ||
"John uploaded a file" or "John will upload a file". To make such | ||
transformations possible, it is necessary for implementations to | ||
have some sense of how the machine-readable JSON serialization | ||
maps to common natural-language linguistic forms. | ||
</p> | ||
|
||
<section id="intransitive"> | ||
<h2>Intransitive Activity</h2> | ||
|
||
<p> | ||
In many situations, the <code><a>actor</a></code> of an Activity also | ||
serves as the direct object. For example, if I say, | ||
"The process terminated", then the "process" is both the actor and the | ||
object. Such statements are formally known as being "intransitive". | ||
</p> | ||
|
||
<figure><figcaption>To describe intransitive activities, | ||
simply omit the <code><a>object</a></code> property:</figcaption> | ||
<pre class="example highlight json">{ | ||
"actor": { | ||
"objectType": "process", | ||
"displayName": "Build Process" | ||
}, | ||
"verb": "terminate" | ||
}</pre></figure> | ||
|
||
</section> | ||
|
||
<section id="transitive"> | ||
<h2>Transitive Activity</h2> | ||
|
||
<p> | ||
In a "transitive" activity, the actor and direct object are distinct | ||
entities. This is the form most commonly expressed using the | ||
Activity Streams format. For instance, if I say, "Joe posted a blog | ||
entry", the actor is "Joe" and the "blog entry" is the direct object. | ||
</p> | ||
|
||
<figure><figcaption>Transitive activities contain distinct <code><a>actor</a></code> and | ||
<code><a>object</a></code> properties:</figcaption> | ||
<pre class="example highlight json">{ | ||
"actor": "acct:joe@example.org", | ||
"verb": "post", | ||
"object": { | ||
"objectType": "article", | ||
"title": "A Blog Entry", | ||
"content": "..." | ||
} | ||
}</pre></figure> | ||
|
||
</section> | ||
|
||
<section id="ditransitive"> | ||
|
||
<h2>Ditransitive Activity</h2> | ||
|
||
<p> | ||
In "ditransitive" activities, there exist distinct actor, direct and | ||
indirect objects. The indirect object specifies the target to which | ||
the action on the direct object has been directed. For instance, in | ||
"Joe posted a blog entry to his Weblog", the indirect object (or | ||
"target") is "Joe's Weblog". | ||
</p> | ||
|
||
<figure><figcaption>Ditransitive activities contain <code><a>actor</a></code>, | ||
<code><a>object</a></code>, and <code><a>target</a></code> properties.</figcaption> | ||
<pre class="example highlight json">{ | ||
"actor": "acct:joe@example.org", | ||
"verb": "post", | ||
"object": { | ||
"objectType": "article", | ||
"title": "A Blog Entry", | ||
"content": "..." | ||
}, | ||
"target": { | ||
"objectType": "blog", | ||
"title": "Joe's Weblog" | ||
} | ||
}</pre></figure> | ||
</section> | ||
|
||
<section id="tense-and-aspect"> | ||
|
||
<h2>Expressing tense and aspect</h2> | ||
|
||
<p> | ||
By using the <code><a>startTime</a></code>, <code><a>endTime</a></code>, | ||
<code><a>duration</a></code> and <code><a>status</a></code> | ||
properties, Activity statements can be used to express past, present | ||
or future actions. Implementations should never rely on an activity | ||
statement's verb identifier to determine the tense or aspect of the | ||
action. | ||
</p> | ||
|
||
<figure><figcaption>To indicate an activity that has already concluded, the | ||
startTime and endTime properties would be used to indicate past | ||
points in time</figcaption> | ||
<pre class="example highlight json">{ | ||
"actor": "acct:joe@example.org", | ||
"verb": "post", | ||
"object": "http://example.org/blog/entry/1", | ||
"startTime": "2012-12-12T12:12:12Z", | ||
"endTime": "2012-12-12T12:12:12Z" | ||
}</pre></figure> | ||
|
||
<figure><figcaption>If specific start and end times for a concluded activity are not | ||
available, the <code><a>status</a></code> property can be used to expressly indicate | ||
that the action has completed:</figcaption> | ||
<pre class="example highlight json">{ | ||
"actor": "acct:joe@example.org", | ||
"verb": "post", | ||
"object": "http://example.org/blog/entry/1", | ||
"status": "completed" | ||
}</pre></figure> | ||
|
||
<figure><figcaption>To indicate an activity that began in the past but is still ongoing, | ||
only the <code><a>startTime</a></code> property would be used:</figcaption> | ||
<pre class="example highlight json">{ | ||
"actor": "acct:joe@example.org", | ||
"verb": "watch", | ||
"object": "http://movies.example.org/movie/1", | ||
"startTime": "2014-03-18T04:32:43Z" | ||
}</pre></figure> | ||
|
||
<figure><figcaption>The status property value "<code>active</code>" can also be used to identify | ||
ongoing activities:</figcaption> | ||
<pre class="example highlight json">{ | ||
"actor": "acct:joe@example.org", | ||
"verb": "watch", | ||
"object": "http://movies.example.org/movie/1", | ||
"status": "active" | ||
}</pre></figure> | ||
|
||
<figure><figcaption>To indicate an activity that is expected to begin in the future, the | ||
<code><a>startTime</a></code> property would indicate a future point in time:</figcaption> | ||
<pre class="example highlight json">{ | ||
"actor": "acct:joe@example.org", | ||
"verb": "cook", | ||
"object": "http://recipes.example.org/recipe/1", | ||
"startTime": "2015-12-23T12:34:21Z" | ||
}</pre></figure> | ||
|
||
<figure><figcaption>Or, alternatively:</figcaption> | ||
<pre class="example highlight json">{ | ||
"actor": "acct:joe@example.org", | ||
"verb": "cook", | ||
"object": "http://recipes.example.org/recipe/1", | ||
"status": "pending" | ||
}</pre></figure> | ||
|
||
<p> | ||
The status values "<code>pending</code>" and "<code>tentative</code>" | ||
differ in that the former is used to mark actions that are expected to | ||
happen while the latter is used to mark proposed actions that may | ||
(or may not) happen. | ||
</p> | ||
|
||
<p> | ||
As an alternative to explicitly stating the <code><a>startTime</a></code> | ||
or <code><a>endTime</a></code> properties, the <code><a>duration</a></code> property | ||
can be used to indicate a specific duration of time relative to either | ||
the <code><a>startTime</a></code> or <code><a>endTime</a></code>. | ||
For instance, specifying an <code><a>endTime</a></code> of | ||
"<code>2015-12-23T12:23:23Z</code>" with a <code><a>duration</a></code> of "<code>PT1H</code>", | ||
implies a starting time of exactly "<code>2015-12-23T11:23:23Z</code>" (1 hour before the specified | ||
ending time). | ||
</p> | ||
|
||
<p> | ||
Note that the value of the <code><a>duration</a></code> property can be expressed | ||
either as a non-negative integer specifying a number of seconds, or | ||
as an [[!RFC3339]] <code>duration</code> string such as "<code>PT1H</code>", "<code>P1DT1H</code>", etc. For | ||
Activity Streams 2.0 implementations for which backwards | ||
compatibility with the Activity Streams 1.0 syntax is not critical, | ||
the RFC 3339 string format is strongly recommended. | ||
</p> | ||
|
||
</section> | ||
|
||
<section id="activity-duration"> | ||
|
||
<h2>Activity Duration</h2> | ||
|
||
<p> | ||
Actions expressed via the Activity Streams format can either be | ||
instantaneous (semelfactive) or durative (having distinct start and | ||
end times). The specific duration of an activity can be optionally | ||
expressed using the <code><a>startTime</a></code>, <code><a>endTime</a></code> | ||
and <code><a>duration</a></code> properties. | ||
</p> | ||
|
||
<p> | ||
By default, all activities are assumed to occur instantaneously, that | ||
is, occuring at one point in time without any specific duration. | ||
Such events are indicated by omitting the <code><a>startTime</a></code>, | ||
<code><a>endTime</a></code> or <code><a>duration</a></code> properties: | ||
</p> | ||
|
||
<figure><figcaption></figcaption> | ||
<pre class="example highlight json">{ | ||
"actor": "acct:sally@example.org", | ||
"verb": "post", | ||
"object": "http://example.org/notes/1" | ||
}</pre></figure> | ||
|
||
<p> | ||
An activity that occurs within a specific period of time can be | ||
expressed using combinations of either: <code><a>startTime</a></code> | ||
and <code><a>endTime</a></code>, <code><a>startTime</a></code> and | ||
<code><a>duration</a></code>, or <code><a>endTime</a></code> and | ||
<code><a>duration</a></code>. For example: | ||
</p> | ||
|
||
<figure><figcaption></figcaption> | ||
<pre class="example highlight json">{ | ||
"actor": "acct:sally@example.org", | ||
"verb": "watch", | ||
"object": "http://movies.example.org/movies/1", | ||
"startTime": "2014-05-23T12:23:12Z", | ||
"endTime": "2014-05-23T13:25:15Z" | ||
}</pre></figure> | ||
|
||
<figure><figcaption></figcaption> | ||
<pre class="example highlight json">{ | ||
"actor": "acct:sally@example.org", | ||
"verb": "watch", | ||
"object": "http://movies.example.org/movies/1", | ||
"startTime": "2014-05-23T12:23:12Z", | ||
"duration": "PT1H2M3S" | ||
}</pre></figure> | ||
|
||
<figure><figcaption></figcaption> | ||
<pre class="example highlight json">{ | ||
"actor": "acct:sally@example.org", | ||
"verb": "watch", | ||
"object": "http://movies.example.org/movies/1", | ||
"duration": "PT1H2M3S", | ||
"endTime": "2014-05-23T13:25:15Z" | ||
}</pre></figure> | ||
|
||
</section> | ||
|
||
</section> |
Oops, something went wrong.